home *** CD-ROM | disk | FTP | other *** search
-
-
-
- Tcl_SetResult(3) Tcl Library Procedures 7.0
-
-
-
- _________________________________________________________________
-
- NAME
- Tcl_SetResult, Tcl_AppendResult, Tcl_AppendElement,
- Tcl_ResetResult - manipulate Tcl result string
-
- SYNOPSIS
- #include <tcl.h>
-
- Tcl_SetResult(_i_n_t_e_r_p, _s_t_r_i_n_g, _f_r_e_e_P_r_o_c)
-
- Tcl_AppendResult(_i_n_t_e_r_p, _s_t_r_i_n_g, _s_t_r_i_n_g, ... , (char *) NULL)
-
- Tcl_AppendElement(_i_n_t_e_r_p, _s_t_r_i_n_g) |
-
- Tcl_ResetResult(_i_n_t_e_r_p)
-
- Tcl_FreeResult(_i_n_t_e_r_p)
-
- ARGUMENTS
- Tcl_Interp *_i_n_t_e_r_p (out) Interpreter whose result
- is to be modified.
-
- char *_s_t_r_i_n_g (in) String value to become
- result for _i_n_t_e_r_p or to
- be appended to existing
- result.
-
- Tcl_FreeProc _f_r_e_e_P_r_o_c (in) Address of procedure to
- call to release storage
- at _s_t_r_i_n_g, or
- TCL_STATIC, TCL_DYNAMIC,
- or TCL_VOLATILE.
- _________________________________________________________________
-
-
- DESCRIPTION
- The procedures described here are utilities for setting the
- result/error string in a Tcl interpreter.
-
- Tcl_SetResult arranges for _s_t_r_i_n_g to be the return string
- for the current Tcl command in _i_n_t_e_r_p, replacing any exist-
- ing result. If _f_r_e_e_P_r_o_c is TCL_STATIC it means that _s_t_r_i_n_g
- refers to an area of static storage that is guaranteed not
- to be modified until at least the next call to Tcl_Eval. If
- _f_r_e_e_P_r_o_c is TCL_DYNAMIC it means that _s_t_r_i_n_g was allocated
- with a call to malloc() and is now the property of the Tcl
- system. Tcl_SetResult will arrange for the string's storage
- to be released by calling free() when it is no longer
- needed. If _f_r_e_e_P_r_o_c is TCL_VOLATILE it means that _s_t_r_i_n_g
- points to an area of memory that is likely to be overwritten
- when Tcl_SetResult returns (e.g. it points to something in a
-
-
-
- Tcl 1
-
-
-
-
-
-
- Tcl_SetResult(3) Tcl Library Procedures 7.0
-
-
-
- stack frame). In this case Tcl_SetResult will make a copy
- of the string in dynamically allocated storage and arrange
- for the copy to be the return string for the current Tcl
- command.
-
- If _f_r_e_e_P_r_o_c isn't one of the values TCL_STATIC, TCL_DYNAMIC,
- and TCL_VOLATILE, then it is the address of a procedure that
- Tcl should call to free the string. This allows applica-
- tions to use non-standard storage allocators. When Tcl no
- longer needs the storage for the string, it will call
- _f_r_e_e_P_r_o_c. _F_r_e_e_P_r_o_c should have arguments and result that
- match the type Tcl_FreeProc:
-
- typedef void Tcl_FreeProc(char *_b_l_o_c_k_P_t_r);
-
- When _f_r_e_e_P_r_o_c is called, its _b_l_o_c_k_P_t_r will be set to the
- value of _s_t_r_i_n_g passed to Tcl_SetResult.
-
- If _s_t_r_i_n_g is NULL, then _f_r_e_e_P_r_o_c is ignored and
- Tcl_SetResult re-initializes _i_n_t_e_r_p's result to point to the
- pre-allocated result area, with an empty string in the
- result area.
-
- If Tcl_SetResult is called at a time when _i_n_t_e_r_p holds a
- result, Tcl_SetResult does whatever is necessary to dispose
- of the old result (see the Tcl_Interp manual entry for
- details on this).
-
- Tcl_AppendResult makes it easy to build up Tcl results in
- pieces. It takes each of its _s_t_r_i_n_g arguments and appends
- them in order to the current result associated with _i_n_t_e_r_p.
- If the result is in its initialized empty state (e.g. a com-
- mand procedure was just invoked or Tcl_ResetResult was just
- called), then Tcl_AppendResult sets the result to the con-
- catenation of its _s_t_r_i_n_g arguments. Tcl_AppendResult may be
- called repeatedly as additional pieces of the result are
- produced. Tcl_AppendResult takes care of all the storage
- management issues associated with managing _i_n_t_e_r_p's result,
- such as allocating a larger result area if necessary. Any
- number of _s_t_r_i_n_g arguments may be passed in a single call;
- the last argument in the list must be a NULL pointer.
-
- Tcl_AppendElement is similar to Tcl_AppendResult in that it
- allows results to be built up in pieces. However,
- Tcl_AppendElement takes only a single _s_t_r_i_n_g argument and it
- appends that argument to the current result as a proper Tcl
- list element. Tcl_AppendElement adds backslashes or braces
- if necessary to ensure that _i_n_t_e_r_p's result can be parsed as
- a list and that _s_t_r_i_n_g will be extracted as a single ele-
- ment. Under normal conditions, Tcl_AppendElement will add a
- space character to _i_n_t_e_r_p's result just before adding the
- new list element, so that the list elements in the result
-
-
-
- Tcl 2
-
-
-
-
-
-
- Tcl_SetResult(3) Tcl Library Procedures 7.0
-
-
-
- are properly separated. However if the new list element is |
- the first in a list or sub-list (i.e. _i_n_t_e_r_p's current |
- result is empty, or consists of the single character ``{'', |
- or ends in the characters `` {'') then no space is added.
-
- Tcl_ResetResult clears the result for _i_n_t_e_r_p, freeing the
- memory associated with it if the current result was dynami-
- cally allocated. It leaves the result in its normal ini-
- tialized state with _i_n_t_e_r_p->_r_e_s_u_l_t pointing to a static
- buffer containing TCL_RESULT_SIZE characters, of which the
- first character is zero. Tcl_ResetResult also clears the
- error state managed by Tcl_AddErrorInfo and
- Tcl_SetErrorCode.
-
- Tcl_FreeResult is a macro that performs part of the work of
- Tcl_ResetResult. It frees up the memory associated with
- _i_n_t_e_r_p's result and sets _i_n_t_e_r_p->_f_r_e_e_P_r_o_c to zero, but it
- doesn't change _i_n_t_e_r_p->_r_e_s_u_l_t or clear error state.
- Tcl_FreeResult is most commonly used when a procedure is
- about to replace one result value with another.
-
-
- SEE ALSO
- Tcl_AddErrorInfo, Tcl_SetErrorCode, Tcl_Interp
-
-
- KEYWORDS
- append, command, element, list, result, return value, inter-
- preter
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
- Tcl 3
-
-
-
-
